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1. 本 项 目 为 sqlalchemy1.1.1 版 本 文档 的 中 文 译 本 ， 只 是 想 通过 翻译 来 熟悉 一 下 sqlalchemy 
以 及 体验 一 下 gitbook 
2， 水 平 有 限 ， 不 定期 更 新 (可 能 每 天 更 新 一 部 分 吧 ，flag 已 经 立 下 了 ) 
3. 如 有 问题 ， 可 以 直接 提 issue 
4. 遵循 Apache License (开源 协议 选择 建议 可 以 看 这 里 ) 
5. 项 目 已 同步 到 gitbook 
tutorial 


发 现 翻 译 完好 好 久 好 久 ， 开 始 使 用 的 话 实际 上 也 不 用 这 么 麻烦 ， 所 以 大 家 可 以 先 看 看 我 写 的 
一 个 入 门 教 程 ， 基 本 上 就 可 以 简单 的 使 用 了 。 


Object Relational Tutorial(X £ 8 4T A T1) 


SQLAIchemy 对 象 关 系 映射 代表 了 用 户 使 用 Python 定义 类 来 与 数据 库 中 的 表 相 关联 的 一 种 方 
式 ， 类 的 实例 则 对 应 数据 表 中 的 一 行 数据 。SQLAIchemy 包 括 了 一 套 将 对 象 中 的 变化 同步 到 数 
据 库 表 中 的 系统 ， 这 套 系统 被 称 之 为 工作 单元 (unit of work) ， 同 时 也 提供 了 使 用 类 查询 来 
实现 数据 库 查询 以 及 查询 表 之 间 关 系 的 功能 。 


SQLAIchemy ORM 与 SQLAIchemy 表 达 式 语言 (SQLAIchemy Expression Language) 是 不 
同 的 ， 前 者 是 在 后 者 的 基础 上 构建 的 ， 也 就 是 说 ， 是 基于 后 者 实现 的 (将 后 者 封装 ， 类 似 于 
实现 一 套 API) 。SQL 表 达 式 语言 (SQL Expression Language) 在 SQL Expression 
Language Tutorial 一 节 有 介绍 ， 他 代表 了 关系 数据 库 最 原始 的 一 种 架构 ， 而 SQLAIchemy 
ORM 则 代表 了 一 种 更 高 级 也 更 抽象 的 实现 ， 同 时 也 是 SQL 表 达 式 语言 的 应 用 。 


尽管 看 起 来 ORM 和 表达 式 语言 使 用 起 来 有 点 相似 ， 但 是 其 相似 点 比 他 们 年 一 看 起 来 还 要 少 

(While there is overlap among the usage patterns of the ORM and the Expression 
Language, the similarities are more superficial than they may at first appear. 不 是 很 确定 翻译 
的 是 否 正确 ， 有 问题 可 直接 联系 ) 。 一 种 方式 是 通过 透视 用 户 定义 的 领域 模型 来 实现 数据 的 
内 容 与 结构 ， 另 外 一 种 方式 通过 文字 模式 〈literal schema) 和 SQL 表达 式 来 明确 的 操作 数据 
库 (The other approaches it from the perspective of literal schema and SQL expression 
representations which are explicitly composed into messages consumed individually by the 
database.) 


一 个 成 功 的 应 用 可 能 只 使 用 对 象 关系 映射 的 构造 。 在 更 复杂 的 情况 下 ， 可 能 ORM 以 及 SQL 表 
达 式 语言 互相 配合 使 用 也 是 必 不 可 少 的 。 


Version Check( 版 本 检查 ) 
使 用 以 下 代码 检查 SQLAIchemy 版 本 


In [2]: import sqlalchemy 
In [3]: sqlalchemy. version . 
Out[3]: '1.0.13' 


PS: 安装 SQLAIchemy 过 程 ， 建 议 先 安装 virtualenv， 再 使 用 pip 安 装 


pip install sqlalchemy==1.0.13 # 版 本 号 可 自选 ， 文 档 对 应 的 为 1 .1.0 


connecting( 连 接 数据 库 ) 


这 篇 教程 中 我 们 使 用 sqlite 数 据 库 来 演示 操作 ， 我 们 使 用 create_engine() 来 连接 需要 操作 的 
数据 库 : 


In [1]: from sqlalchemy import create engine 


In [2]: engine = create engine('sqlite:///:test:', echo-True) 


echo 参数 是 用 来 设置 SQLAIchemy 日 志 的 ， 通 过 Python 标准 库 logging 模 块 实 现 。 设 置 为 
True 的 时 候 我 们 可 以 看 见 所 以 的 操作 记录 。 如 果 你 在 按照 本 教程 进行 学 习 ， 那 么 你 可 以 将 它 
设置 为 False 来 减少 日 志 的 输出 。 


create engine() 的 返回 值 是 Engine 的 一 个 实例 ， 此 实例 代表 了 操作 数据 库 的 核心 接口 ， 通 
过 方言 来 处 理 数据 库 和 数据 库 的 APl。 在 本 例 中 ，SQLite 方 言 将 被 翻译 成 Python 内 置 的 sqlite3 
模块 (个 人 理解 ， 方 言 指 的 是 每 一 种 数据 库 的 使 用 的 方言 ， 比 方 说 mysql 会 有 一 种 ，sqlite 又 
会 有 一 种 ， 而 每 种 语言 又 会 有 很 多 在 数据 库 的 处 理 模块 ， 比 方 说 刚刚 提 到 的 Python 内 置 的 
sqlite3 模 块 ) 。 


当 第 一 次 调用 Engine.execute() 或 者 Engine.connect() 这 种 方法 的 时 候 ， 引 擎 (Engine) 
会 和 数据 库 建立 一 个 丨 正 的 DBAPI 连 接 ， 用 来 执行 SQL 语 句 。 但 是 在 创建 了 连接 之 后 ， 我 们 
很 少 直接 使 用 ea i 更 多 的 会 使 用 DRM 这 种 方式 来 操作 数据 库 ， 这 种 方式 在 
下 面 我 们 会 看 见 具体 的 例子 


PS1: 什么 是 Database Urls 


PS2: Lazy Connecting: 初次 调用 create engine() 的 时 候 并 不 会 真正 的 去 连接 数据 库 ， 只 有 
在 申 正 执行 一 条 命令 的 时 候 才 会 去 尝试 建立 连接 。 目的 是 省 资源 ， 很 多 地 方 都 会 使 用 这 种 
方式 ， 比 方 说 Python 中 的 lazy property 


Declare a Mapping 


当 使 用 ORM 的 时 候 ， 配 置 过 程 以 描述 数据 库 的 表 来 开始 ， 然 后 我 们 定义 与 之 匹配 的 类 。 在 现 
a wa ， 这 两 个 过 程 一 般 结合 在 一 起 ， 通 过 一 个 称 之 为 声明 (Declarative) 的 系 
统 实现 。 这 个 系统 帮 了 我 们 定义 类 以 及 实现 与 表 的 对 应 。 


声明 系统 实现 类 与 表 的 对 应 是 通过 一 系列 基 类 实现 的 -- 即 声明 基 类 (declarative base class) ° 
我 们 的 应 用 程序 经 常 只 有 一 个 此 基 类 的 示例 。 使 用 declarative_base() 函数 ， 如 下 : 


In [2]: from sqlalchemy.ext.declarative import declarative base 


In [3]: Base - declarative base() 


有 了 "base" 之 后 ， 我 们 可 通过 他 定义 任何 数量 的 映射 类 。 我 们 以 一 个 user 表 来 开始 这 个 教程 ， 
User 表 记录 了 用 我 们 应 用 的 终端 用 户 的 信息 。 与 之 对 应 的 类 称 之 为 User。 表 的 信息 包括 表 
名 ， 姓 名 ， 还 有 列 的 数据 类 型 ， 如 下 : 


from sqlalchemy import Column, Integer, String 


class User(Base): 
. tablename = 'users' 


id - Column(Integer, primary key-True) 
name = Column(String) 

fullname - Column(String) 

password - Column(String) 


def repr (self): 
return "<User (name='%s', fullname='%s', password-'9ss')2" % (self.name, self.ful 
lname, self.password) 


i: User class X 3. f —* repr() 函 数 ， 但 是 这 并 非 必 须 的。 使 用 它 是 为 了 在 这 个 教程 里 使 我 
们 的 例子 (User 对 象 ) 有 更 好 看 的 格式 。 


使 用 Declarative 定 义 的 类 最 少 要 包括 一 个 tablename 参数 ， 还 有 一 列 (作为 数据 库 primary 
key) 。SQLAIchemy 自 己 从 不 做 关于 类 所 对 应 的 表 的 任何 假定 ， 包 括 它 没有 任何 于 名 称 、 数 
据 类 型 或 者 约束 内 置 的 约束 。 但 是 并 不 代表 没有 一 个 规范 的 模式 ， 相 反 ， 它 鼓励 你 使 用 帮助 
函数 和 mixin 类 创建 自己 的 自动 规范 约束 ， 帮 助 函 数 和 mixin 类 在 Mixin 和 Custom Base Classes 
里 有 详细 的 描述 。 


当 构 建 类 的 时 候 ，Declarative 使 用 特殊 的 Python accessor ( 即 descriptors) 代替 了 所 有 的 
Column 对 象 ; 这 个 过 程 称 之 为 instrumentation (中 文 意思 : 乐器 ) 。 这 个 "instrumented" 过 的 
类 为 我 们 的 表 提 供 了 一 种 使 用 Sql 语句 访问 数据 库 中 表 的 方式 ， 同 时 也 提供 读 取 表 中 数据 的 方 
AX (好 特 码 复杂 ， 原 文 provide us with the means to refer to our table in a SQL context as 
well as to persist and load the values of columns from the database.) 


除 此 之 外 ， 还 有 一 些 普通 的 Python 类 ， 可 以 让 我 们 定义 一 些 用 于 我 们 应 用 的 一 般 的 参数 。 


Create a Schema 


通过 Declarative 系 统 构 建 了 类 之 后 ， 我 们 也 定义 了 被 称 之 为 表 的 元 数据 信息 。 被 SQLAIchemy 
用 来 为 些 信息 的 对 象 被 称 之 为 Table 对 g ， Declarative 系 统 为 我 们 实现 了 这 
些 。 我 们 可 以 通过 检测 table 参数 来 查看 这 个 对 象 : 如 下 


# 代码 接 上 面 
»»User. table _ 
Table('users', MetaData(bindzNone), 
Column('id', Integer(), table-«users», primary key-True, nullable-False), 
Column('name', String(), table-«users»?), 
Column('fullname', String(), table-«users»?), 
Column('password', String(), table-«users»), schema-zNone) 


PS: 经 典 映 射 -Classical Mappings 虽然 在 Declarative 系 统 里 十 分 推荐 使 用 ， 但 是 对 使 用 
SQLAlchemy ORM 来 说 也 并 非 必 须 的 。 在 Declarative 系 统 外 ， 任 何 一 个 Python 类 都 可 以 通 
过 mapper() 函数 来 映射 到 一 个 数据 表 ， 但 是 用 的 相对 较 少 ， 可 以 在 Classical Mappings 看 到 
介绍 。 


当 声 明 一 个 类 的 时 候 ，Declarative 系 统 使 用 Python 元 类 来 实现 ， 这 样 就 可 以 在 类 被 声明 之 后 
还 可 以 执行 一 些 额 外 的 操作 (不 懂 的 同学 可 以 看 一 TARREGA AET dde 
我 们 的 指定 创建 一 个 Table 对 象 ， 然 后 通过 构建 一 个 Mapper 对 象 使 之 与 类 关联 。 这 个 对 象 是 一 
个 幕后 的 对 象 (behind-the-scenes object) ， 以 至 于 我 们 一 般 不 直接 与 他 打交道 (虽然 在 我 
们 需要 的 时 候 它 也 能 我 们 提供 很 多 信息 ) 


Table 对 象 是 一 系列 的 元 数据 的 组 合 。 当 使 用 Declarative 的 时 候 ， 这 个 对 象 可 以 使 用 我 们 
declarative 的 基 类 的 .metadata 属性 (When using Declarative, this object is available using 
the .metadata attribute of our declarative base class.) 。 


元 数据 是 一 堆 包 含 的 可 以 在 数据 库 里 执行 的 命令 集 。 因 为 我 们 的 SQLite 数 据 库 目 前 还 没有 一 
个 users 表 ， 我 们 可 以 使 用 这 些 元 数据 来 创建 这 些 表 。 下 面 ， 我 们 调 

用 MetaData.create  all() 方法 来 将 这 些 传 给 数据 库 。 然 后 就 可 以 看 到 提交 这 些 命令 之 后 的 过 
程 ， 如 下 : 


>>> Base.metadata.create all(engine) 
SELECT. 瑟 于 
PRAGMA table info("users") 
() 
CREATE TABLE users ( 
id INTEGER NOT NULL, name VARCHAR, 
fullname VARCHAR, 
password VARCHAR, 
PRIMARY KEY (id) 
) 


() 
COMMIT 


Minimal Table Descriptions vs. Full Descriptions 


熟悉 CREATE TABLE 语 法 的 同学 可 能 注意 到 了 我 们 刚刚 创建 VARCHAR 列 的 时 候 没 有 指定 长 
度 ， 在 SQLite 和 Postgresql 里 是 允许 的 ， 但 是 在 其 他 地 方 是 被 禁止 的 。 所 以 如 果 你 使 用 了 其 他 
的 数据 库 同时 想 使 用 SQLAIchemy 来 创建 一 个 表 ， 那 么 可 能 需要 给 String type 添 加 一 个 长度， 
格式 如 下 : 


Column(String(50)) 


String 和 其 他 的 Integer，Numeric 等 待 都 一 样 ， 除 了 创建 表 的 时 候 其 他 时 候 用 不 到 。 


除 此 之 外 ，Firebird 和 Oracle 需 要 指定 一 个 主 key， 但 是 SQLAIchemy 并 不 会 自动 生存 。 对 于 这 
种 情况 ， 你 可 以 使 用 sequence 来 实现 : 


from sqlalchemy import Sequence 
Column(Integer, Sequence('user id seq'), primary key-True) 


使 用 declarative 来 实现 一 个 映射 的 完整 应 用 如 下 : 


class User(Base): 
. tablename = 'users' 
id - Column(Integer, Sequence('user id seq'), primary key-True) 
name = Column(String(50)) 
fullname = Column(String(50)) 
password - Column(String(12)) 


def repr (self): 
return "<User (name='%s', fullname-'9:s', password-'9?es')»" 96 ( 
self.name, self.fullname, self.password) 


我 们 展示 了 这 个 完整 的 表 以 此 对 比 来 显示 两 者 的 区 别 〈 最 小 结构 vs 完整 版 ) ， 完 整 的 可 以 用 
来 完成 创建 茶 种 特定 的 很 严格 的 需求 的 表 。 


Create an Instance of the Mapped Class 


声明 完 映 射 之 后 ， 我 们 来 创建 一 个 User 对 象 ， 如 下 : 


>>> ed user = User(name-'ed', fullname-'Ed Jones', password-'edspassword') 
>>> ed user.name 

' ed' 

>>> ed user.password 

'edspassword' 

>>> str(ed user.id) 

'None' 


i: init() 方法 


我 们 使 用 Declarative 系 统 创建 的 类 包含 了 一 个 构造 函数 ， 可 以 自动 的 接受 并 匹配 关键 词 。 当 
然 也 可 以 自 定义 一 个 init() 函数 ， 这 样 的 话 就 会 覆盖 自 带 的 。 


即使 我 们 没有 在 构造 函数 里 指定 id， 但 是 我 们 访问 它 的 时 候 系 统 仍 然 给 了 一 个 上 默认 的 值 (CE 
值 ， 和 Python 里 其 他 的 如 果 没 有 定义 就 会 引起 一 个 参数 错误 相反 ， 这 里 不 会 有 错误 ) 。 
SQLAIchemy 经 常会 在 我 们 第 一 次 使 用 的 时 候 去 给 参数 赋 一 个 值 。 对 于 那些 我 们 已 经 赋值 的 参 
数 ， 仪 器 系统 (instrumentation system) 会 在 插入 语句 执行 的 时 候 跟 踪 这 些 和 参数 

(SQLAlchemy's instrumentation normally produces this default value for column-mapped 
attributes when first accessed. For those attributes where we've actually assigned a value, 
the instrumentation system is tracking those assignments for use within an eventual INSERT 
statement to be emitted to the database.) ^ 


Creating a Session 


现在 我 们 开始 讨论 数据 库 。ORM 处 理 数据 库 的 方式 是 通过 Session 来 实现 的 。 当 我 们 第 一 次 创 
建 这 个 应 用 的 时 候 ， 我 们 使 用 create engine() 语句 ， 同 时 也 定义 一 个 Session 类 来 当做 一 个 
工厂 来 处 理 Session 对 象 (When we first set up the application, at the same level as our 
create engine() statement, we define a Session class which will serve as a factory for new 
Session objects ) 


>>> from sqlalchemy.orm import sessionmaker 
>>> Session = sessionmaker(bind-engine) 


如 果 此 时 你 还 没有 一 个 engine 对 象 ， 那 么 可 以 使 用 下 面 这 种 方法 : 


>>> Session = sessionmaker() 


然后 再 创建 一 个 engine (使 用 create engine() ) ,然后 使 用 configure 来 连接 session 和 
engine : 


>>> Session.configure(bind-engine) # once engine is available 


这 个 定制 后 的 类 会 创建 一 个 绑 定 到 我 们 指定 数据 库 的 Session 对 象 ， 其 他 的 交易 特征 也 可 以 在 
调用 Sessionmaker 的 时 候 定 义 。 这 些 东 西 会 在 下 一 章 讨 论 。 然 后 当 你 需要 与 数据 库 进 行 对 话 
的 时 候 ， 你 需要 创建 一 个 Session 实 例 : 


>>> session = Session() 


上 面 的 Session 是 和 我 们 的 SQLite-enabled 引 擎 相关 联 的 ， 但 是 现在 还 没有 与 数据 库 链 接 。 当 
他 第 一 次 被 调用 的 时 候 才 会 建立 与 一 个 Engine 维 护 的 连接 池 连 接 ， 一 直 持 续 到 我 们 关闭 
Session 对 象 ， 或 者 提交 完 所 有 的 变化 。 


PS: 会 话 的 生命 周期 模式 (Session Lifecycle Patterns ) 


说 明 时 候 创 建 一 个 会 话 依赖 于 我 们 在 创建 一 个 说 明 应 用 。 记 住 ， 对 话 只 是 你 对 象 指向 一 个 数 
据 库 链接 的 一 个 工作 空间 ， 如 果 把 对 象 进 程 比 作 一 个 晚 宾 ， 那 么 来 宾 的 盘子 还 有 盘子 上 的 食 
物 则 是 回话 〈 数 据 库 就 是 厨房 ? ) | 更 多 的 了 解 请 连 链 接 一 什么 时 候 创 建 会 话 ， 什 么 时 候 提 
交 ， 什 么 时 候 关闭 。 


添加 一 更 新 对 象 (Adding and Updating 
Objects ) 


为 了 持续 操作 (persist) 我 们 的 user 对象， 我 们 把 他 添加 〈 add() ) 到 会 话 中 : 


>>> ed user = User(name-'ed', fullname-'Ed Jones', password-'edspassword') 
>>> session.add(ed user) 


现在 ， 我 们 称 这 个 对 象 是 待定 的 (pending) ; 现在 没有 任何 SQL 语句 被 执行 ， 同 时 这 个 对 象 
也 并 代表 数据 库 中 的 一 行 数据 。 对 话 (Session) 会 在 需要 的 时 候 尽快 持久 化 Ed Jones ， 这 
个 过 程 称 之 为 flush 。 如 果 我 们 在 数据 库 里 查询 Ed Jones ， 所 以 的 待定 信息 (pending 
information) 都 会 首先 被 flush (冲刷 ? ) ， 随 机 查询 请 求 被 执行 。 


For example, below we create a new Query object which loads instances of User. We “filter 
by" the name attribute of ed, and indicate that we'd like only the first result in the full list of 
rows. A User instance is returned which is equivalent to that which we've added: 例如 ， 下 面 
我 们 创建 一 个 user 实例 的 查询 对 象 ， 我 们 使 用 名 字 属 性 来 过 滤 ed ， 然 后 只 选取 列表 里 的 第 
一 个 数据 。 返 回 结果 就 是 我 们 之 前 添加 的 那个 User 对 象 : 


>>> OUr user = session.query(User).filter by(name-'ed').first() # doctest:-*NORMALIZE W 
HITESPACE 


>>> our user 


<User (name='ed', fullname-'Ed Jones', password-'edspassword')» 


实际 上 上， 会话 (Session) 已 经 识别 出 这 行 数据 已 经 在 内 部 的 map 对 象 中 了 (In fact, the 
Session has identified that the row returned is the same row as one already represented 
within its internal map of objects, so we actually got back the identical instance as that which 
we just added:) ， 所 以 我 们 拿 回 的 数据 就 是 之 前 刚刚 添加 的 那个 : 


>>> ed user is our user 
True 


ORM 的 概念 在 工作 的 地 方 会 识别 并 且 保 证 会 是 在 一 个 特殊 的 行 上 。 一 旦 一 个 对 象 已 经 在 会 话 
中 有 一 个 主键 (primary key) ， 所 有 关于 这 个 key 的 SQL 查 询 都 只 返回 一 个 同样 的 Python 对 
象 ， 如 果 已 经 存在 某 个 主键 的 对 象 ， 此 时 想 添加 一 个 同样 主键 的 对 象 ， 就 会 引起 一 个 错误 。 
我 们 可 以 使 用 add_all() 函数 一 次 性 添加 多 个 user 对 象 : 
>>> session.add all([ 
User(name-'wendy', fullname-'Wendy Williams', password-'foobar'), 


User(name-'mary', fullname-'Mary Contrary', password-'xxg527'), 
User(name-'fred', fullname-'Fred Flinstone', password-'blah')]) 


同样 ， 我 们 如 果 觉 得 Ed 的 密码 不 太 安全 ， 也 可 以 更 改 密码 : 


>>> ed user.password = 'f8s7ccs' 


而 会 话 则 时 刻 注 意 着 这 些 变 化 ， 例 如 ， 他 检测 到 了 Ed Jones 已 经 被 更 改 了 : 


>>> session.dirty 


IdentitySet([«User(name-'ed', fullname-'Ed Jones', password='f8s7ccs')>]) 


同时 ，3 个 新 的 user 对 象 处 于 等 待 提 交 的 状态 : 


>>> session.new # doctest: +SKIP 

IdentitySet([«User(name-'wendy', fullname-'Wendy Williams', password-'foobar')», 
«User(name-z'mary', fullname-'Mary Contrary', password-'xxg527')», 
«User(name-'fred', fullname-'Fred Flinstone', password-'blah')»]) 


我 们 通知 会 话 (Session) 我 们 想 保留 所 以 的 更 改 然后 提交 到 数据 库 。 使 用 comit) 提交 这 
些 更 改 ， 会 话 提交 UPDATE 语句 来 更 改 ed 的 密码 ， 同 时 使 用 INSERT 语句 来 实现 新 的 对 象 的 
插入 : 


>>> session.commit() 


If we look at Ed’s id attribute, which earlier was None, it now has a value: 
如 果 我 们 看 Ed 的 id 属 性 ， 之 前 我 们 没有 设置 ， 但 是 现在 他 有 一 个 值 了 : 
ed user.id # doctest: +NORMALIZE WHITESPACE 1" 


当 会 话 在 数据 中 中 插入 了 新 的 行 之 后 ， 所 有 新 生成 的 标识 符 还 有 数据 库 为 对 象 生 成 的 一 些 默 
认 值 都 是 可 以 获取 到 的 ， 同 时 是 可 以 立即 访问 的 或 者 可 以 一 次 获取 到 的 (load-on-first- 
access) 。 在 这 种 情况 下 ， 一 行 数据 是 重新 加 载 的 因为 在 提交 之 后 就 开始 了 一 个 新 的 事务 。 
SQLAIchemy 在 新 的 事务 中 会 从 上 一 个 事务 中 去 获取 更 新 的 数据 ， 这 样 大 部 分 最 近 使 用 的 语句 
都 可 获取 到 。 重 新 加 载 的 级 别 是 可 以 定义 的 ， 可 以 去 这 里 查看 。 


PS: 会 话 对 象 的 状态 一 Session Object States 


如 果 我 们 的 user 对 得 从 session 外 移 到 里 边 ， 为 了 缆 正 的 插入 ， 他 会 经 历 三 个 状态 (一 共有 
四 个 状态 ) 一 和 短暂， 等 待 ， 持久 化 (transient, pending, and persistent) 。 知 道 这 几 个 状态 的 
含义 非常 有 帮助 ， 推 荐 去 这 里 详细 理解 一 下 。 


wÈ (Rolling Back) 


既然 会 话 在 一 个 事务 里 边 起 作用 ， 那 么 我 们 也 可 以 在 这 个 事务 里 回 滚 一 些 变 化 。 让 我 们 做 两 
个 更 改 ， 然 后 再 删 掉 更 改 ， 把 ed_user 的 用 户 名 改 成 Edwardo 


>>> ed user.name = 'Edwardo' 
然后 添加 另外 一 个 错误 的 假 用 户 : 


>>> fake user = User(name-'fakeuser', fullname-'Invalid', password-'12345') 
>>> session.add(fake user) 


查询 会 话 ， 我 们 可 以 看 到 这 些 已 经 放 到 了 现在 所 处 的 事务 当中 : 


>>> session.query(User).filter(User.name.in (['Edwardo', 'fakeuser'])).all() 
[xUser(name-'Edwardo', fullname-'Ed Jones', password-'f8s7ccs')», «User(name-'fakeuser 
', fullname-'Invalid', password-'12345')2] 


回 滚 一 下 ， 我 们 就 看 到 ed user. 的 用 户 名 已 经 改 回 了 ed ， 假 用 户 也 不 存在 了 : 


>>> session.rollback() 


SQL>>> ed user.name 
u'ed' 

>>> fake user in session 
False 


执行 一 个 选择 语句 来 看 看 对 数据 库 的 影响 : 


>>> session.query(User).filter(User.name.in (['ed', 'fakeuser'])).all() 
[xUser(name-'ed', fullname-'Ed Jones', password-'f8s7ccs')»] 


查询 (Quering) 


e Query 对 象 是 通过 Session 里 的 query() 方法 来 创建 的 ? 这 个 方法 有 一 些 参数 ， 参数 可 
以 是 一 些 内 置 的 类 或 者 描述 符 。 下 面 我 们 声明 一 个 user 实例 的 查询 对 象 。 当 我 们 执行 这 些 语 
名 的 时 候 ， 就 可 以 看 到 user 对 象 返回 来 的 查询 列表 : 


>>> for instance in session.query(User).order by(User.id): 
print(instance.name, instance.fullname) 

ed Ed Jones 

wendy Wendy Williams 

mary Mary Contrary 

fred Fred Flinstone 


for name, fullname in session.query(User.name, User.fullname): ... 
print(name, fullname) ed Ed Jones wendy Wendy Williams mary Mary 
Contrary fred Fred Flinstone ^" 


Query 返回 的 结果 称 之 为 元 组 (tuples) ， 通 过 Keyedruple class 实 现 ， 同 时 可 以 被 当做 
Python 的 原生 对 象 来 处 理 。 参 数 的 名 称 和 参数 一 样 ， 类 名 和 类 一 样 〈 不 知道 咋 翻 译 ， 原 文 : 
The names are the same as the attribute's name for an attribute, and the class name for a 
class， 看 例子 理解 的 意思 就 是 : row 对 应 的 是 User 想 获取 name 就 使 用 row.name， 这 样 row 
和 row.name 分 别 都 有 其 对 应 的 User，Username 了 ) 


>>> for row in session.query(User, User.name).all(): 

print(row.User, row.name) 
«User(name-'ed', fullname-'Ed Jones', password-z'f8s7ccs')» ed 
«User(name-z'wendy', fullname-'Wendy Williams', password-z'foobar')» wendy 
«User(name-'mary', fullname-'Mary Contrary', password-z'xxg527!')» mary 
«User(name-z'fred', fullname-'Fred Flinstone', password-'blah')» fred 


可 以 使 用 类 元 素 衍 生 的 一 个 对 象 1able() 构造 《construct) 来 给 一 列 起 另外 的 称呼 ， 任 何 一 
个 类 的 参数 都 可 以 这 样 使 用 (功能 就 像 名 字 一 样 ， 打 标签 ， 起 别名 ) 


>>> for row in session.query(User.name.label('name label')).all(): 
print(row.name label) 

ed 

wendy 

mary 

fred 


这 里 把 这 个 名 字 给 了 User (实际 上 是 给 了 User 里 的 name) ， 但 是 如 果 有 两 个 参数 呢 
(query() 里 有 两 个 参数 的 情况 ? 上 面 的 例子 只 有 一 个 ) ? 可 以 使 用 aliased() 来 解决 (和 
bash 里 的 alias 差 不 多 ) : 


>>> from sqlalchemy.orm import aliased 
>>> user alias = aliased(User, name-'user alias ') 


>>> for row in session.query(user alias, user alias.name).all(): 
print(row.user alias) 

«User(name-'ed', fullname-'Ed Jones', password-'f8s7ccs')» 

«User(name-z'wendy', fullname-'wendy Williams', password-'foobar')» 

«User(name-'mary', fullname-'Mary Contrary', password-z'xxg527!)» 

«User(name-z'fred', fullname-'Fred Flinstone', password-'blah')» 


for u in session.query(User).order by(User.id)[1:3]: ... print(u) 


过 滤 结 果 使 用 filter by() 来 实现 ， 使 用 的 参数 是 关键 字 : 


>>> for name, in session.query(User.name).filter by(fullname-'Ed Jones'): 
print(name) 
ed 


或 者 使 用 filter() * filter() 使 用 更 灵活 的 SQL 语 句 的 结构 来 过 滤 。 这 可 以 让 你 使 用 规律 
的 Python 操 作 符 来 操作 你 映射 的 类 参数 : 


>>> for name, in session.query(User.name).filter(User.fullname--'Ed Jones'): 
print(name) 
ed 


Query 对 象 是 完全 可 繁殖 的 (fully generative) ， 意 味 着 大 多 数 方法 的 调用 都 返回 一 个 新 

的 Query *1 & ( a new Query object upon which further criteria may be added.) 此 对 象 仍 可 
进行 查询 操作 (不 知道 理解 对 不 对 ) ， 例 如 ， 你 可 以 调 两 次 filter) 函数 来 查 用 户 名 为 ed 并 
且 全 名 为 Ed Jones 的 用 户 ， 相 当 于 SQL 中 的 AND 操 作 : 


>>> for user in session.query(User).N 
filter (User .name=='ed').\ 
filter(User.fullname--'Ed Jones'): 
print(user) 
<User (name='ed', fullname-'Ed Jones', password-'f8s7ccs')» 


常用 过 滤 操 作 (Common Filter Operators) 


里 是 一 份 常用 过 滤 操 作 的 摘要 : 


ps 


* equals 


query.filter(User.name -- 'ed') 


* not equals 


query.filter(User.name !- 'ed') 


* LIKE 


query.filter(User.name.like('9?ced96' )) 


query.filter(User.name.in (['ed', 'wendy', 'jack'])) 
# works with query objects too: 


query.filter(User.name.in ( 
session.query(User.name).filter(User.name.like( '9?ced9*6' )) 


2) 


9 NOT IN 


query.filter(-User.name.in (['ed', 'wendy', 'jack'])) 


9 IS NULL 


query.filter(User.name -- None) 
# alternatively, if pep8/linters are a concern 


query.filter(User.name.is (None)) 


9 IS NOT NULL 


query.filter(User.name !- None) 
# alternatively, if pep8/linters are a concern 


query.filter(User.name.isnot(None)) 


9 AND 


# use and () 
from sqlalchemy import and. 
query.filter(and (User.name == 'ed', User.fullname == "Ed Jones')) 


# or send multiple expressions to .filter() 
query.filter(User.name == 'ed', User.fullname == "Ed Jones!) 


# or chain multiple filter()/filter by() calls 
query.filter(User.name -- 'ed').filter(User.fullname -- 'Ed Jones') 
注意 是 and () 不 是 Python 里 的 and 操作 符 


* OR 


from sqlalchemy import or 
query.filter(or (User.name == 'ed', User.name == 'wendy')) 


注意 是 or_() 不 是 Python 里 的 or 操作 符 


9 MATCH 


query.filter(User.name.match( 'wendy')) 


注意 match() 使 用 MATCH 或 者 CONTAINS 来 实现 的 ， 所 以 和 数据 库 底层 有 关 ， 在 一 些 数据 
库 下 不 能 使 用 ， 比 如 说 SQLite 


查询 返回 的 列表 以 及 标量 (Returning Lists and 
Scalars ) 


* "al1()、 返 回 一 个 列表 : 


query = session.query(User).filter(User.name.like('96ed")).order by(User.id) 
query.all() [ ] `> 


e first() 对 查询 结果 进行 了 一 个 限制 -返回 列表 的 第 一 个 值 : 


>>> query.first() 
<User (name='ed', fullname='Ed Jones', password-'f8s7ccs')» 


e one() 完全 匹配 所 以 行 ， 如 果 匹 配 不 到 ， 则 返回 一 个 错误 ， 或 者 匹配 到 多 个 值 也 会 返回 
错误 : 

# 多 个 值 

>>> user = query.one() 

Traceback (most recent call last): 

MultipleResultsFound: Multiple rows were found for one() 

# 匹配 不 到 

>>> user = query.filter(User.id == 99).one() 


Traceback (most recent call last): 


NoResultFound: No row was found for one() 


one() 对 于 那些 希望 分 | | 与 查询 到 多 个 值 的 系统 是 十 分 好 的 ， 比 方 说 在 RESTful 
API 中 ， 查 询 不 到 可 能 会 返回 404 页 面 ， 多 个 结果 则 可 能 希望 返回 一 个 应 用 错误 。 


* one or none() 和 one() 很 像 ， 除 了 在 查询 不 到 的 时 候 。 查 询 不 到 的 时 
候 one_or_none() 会 直接 返回 None， 但 是 在 找到 多 个 值 的 时 候 和 one() 一 样 。 


e scalar() 援引 自 one( ) 函数 ， 查 询 成 功 之 后 会 返回 这 一 行 的 第 一 列 参 数 ， 如下: 


>>> query = session.query(User.id).filter(User.name == 'ed').N 
order by(User.id) 

>>> query.scalar() 

1 


使 用 SQL 语 名 查询 (Using Textual SQL) 


from sqlalchemy import text SQL>>> for user in 
session.query(User).filter(text("id«224")).order by(text("id")).all(): ... 
print(user.name) ed wendy mary fred `` 


使 用 基于 字符 串 的 SQL 语 名 (string-based SQL) 可 以 通过 冒号 来 指定 参数 。 为 参数 复制 可 以 
使 用 params() 来 实现 : 


>>> session.query(User).filter(text("id<:value and name=:name")).params(value=224, nam 
e='fred').order_by(User.id).one() 
<User (name='fred', fullname='Fred Flinstone', password='blah')> 


为 了 使 用 完全 基于 字符 囊 的 语句 ， 可 以 使 用 from_statement() 来 实现 。 不 需要 额外 的 指定 ， 
完全 的 字符 囊 SQL 语 和 句 是 根据 模型 (model) 的 名 字 来 匹配 的 ， 如 下 ， 我 们 仅 使 用 了 一 个 星 号 
就 获取 到 了 所 有 的 信息 (查找 名 字 为 ed 的 行 ) 


>>> session.query(User).from statement( 

text("SELECT * FROM users where name-:name")).N 
um params(namez'ed').all() 
[xUser(name-'ed', fullname-'Ed Jones', password-'f8s7ccs')»] 


在 简单 的 例子 中 去 根据 名 字 匹 配 是 可 行 的， 但 是 当 处 理 包含 着 重复 的 名 字 的 复杂 的 语句 的 时 
候 或 者 使 用 匿名 的 ORM 架 构 的 时 候 就 不 太 现实 了 (unwieldy when dealing with complex 
statements that contain duplicate column names or when using anonymized ORM 
constructs that don't easily match to specific names) 。 除 此 之 外 ， 有 一 个 典型 的 表现 就 是 在 


我 们 匹配 结果 的 时 候 ， 我 们 可 能 会 发 现 处 理 找到 的 结果 也 是 十 分 有 必要 的 。 在 这 
下 ， text() 架构 允许 我 们 把 纯 SQL 语 名 与 ORM 了 映射 对 应 起 来 ， 我 们 通 
过 TextClause.columns() 方法 可 以 传 一 些 表 达 式 参数 : 


>>> stmt = text("SELECT name, id, fullname, password " 

"FROM users where name-:name") 
>>> stmt = stmt.columns(User.name, User.id, User.fullname, User.password) 
SQL>>> session.query(User).from statement(stmt).params(namez'ed').all() 
[<User (name='ed', fullname-'Ed Jones', password-'f8s7ccs')»] 


a text() 架构 里 查找 的 时 候 ， Query 可 能 会 指定 一 些 返 回 的 实体 ， 比 如 不 返回 全 部 的 ， 只 
返回 一 部 分 信息 


>>> stmt = text("SELECT name, id FROM users where name-:name" 
>>> stmt = stmt.columns(User.name, User.id) 

SQL>>> session.query(User.id, User.name).* 

UA from statement(stmt).params(name-z'ed').all() 

[(1, u'ed')] 


计数 (Counting) 


session.query(User).filter(User.name.like('9oed')).count() 2 `` 


count() 函数 是 用 来 计算 返回 值 里 包含 多 少 项 的 ，SQLAIchemy 总 是 把 查询 结果 放 到 一 个 子 集 
里 边 ， count() 函数 就 是 用 来 计算 子 集 的 。 有 些 例子 下 面 可 以 直接 使 用 SELECT count(*) FROM 
table 来 计算 有 多 少 个 值 ， 但 是 SQLAIchemy 并 不 去 判断 这 是 否 是 恰当 的 ， 毕 竞 准 确 的 结果 可 
以 使 用 那个 准确 的 方法 去 获得 (however modern versions of SQLAlchemy don't try to guess 
when this is appropriate, as the exact SQL can be emitted using more explicit means. ) 


需要 我 们 对 每 一 项 分 别 计 数 的 时 候 ， 我 们 需要 在 func 模块 里 通过 func.count() 来 直接 指 
Z count() 函数 ， 下 面 我 们 可 以 单独 计算 一 下 每 个 名 称 的 数量 : 


>>> from sqlalchemy import func 
SQL>>> session.query(func.count(User.name), User.name).group by(User.name).all() 
[(1, u'ed'), (1, u'fred'), (1, u'mary'), (1, u'wendy')] 


为 了 实现 SELECT count(*) FROM table 的 功能 ， 我 们 可 以 这 样 做 : 


>>> session.query(func.count('*')).select from(User).scalar() 
4 


如 果 我 们 直接 根据 user 的 主键 来 计算 ， 那 么 select_from() 可 以 去 掉 : 


>>> session.query(func.count(User.id)).scalar() 
4 


Building a Relationship 


